// TMake项目核心类型定义
// 该文件包含了TMake编译器和相关模块使用的所有接口、类型和枚举定义

/**
 * AST节点类型枚举
 * 定义TMake语言支持的所有AST节点类型
 */
export enum ASTNodeType {
  STRING = 'string',
  NUMBER = 'number',
  BOOLEAN = 'boolean',
  IDENTIFIER = 'identifier',
  NULL = 'null',
  UNDEFINED = 'undefined',
  ARRAY = 'array',
  OBJECT = 'object',
  
  // 表达式节点
  BINARY_EXPRESSION = 'binary_expression',
  UNARY_EXPRESSION = 'unary_expression',
  MEMBER_EXPRESSION = 'member_expression',
  CALL_EXPRESSION = 'call_expression',
  
  // 语句节点
  IF_STATEMENT = 'if_statement',
  SWITCH_STATEMENT = 'switch_statement',
  CASE_CLAUSE = 'case_clause',
  DEFAULT_CLAUSE = 'default_clause',
  BLOCK_STATEMENT = 'block_statement',
  RETURN_STATEMENT = 'return_statement',
  BREAK_STATEMENT = 'break_statement',
  CONTINUE_STATEMENT = 'continue_statement',
  
  // 函数和声明
  FUNCTION_CALL = 'function_call',
  VARIABLE_DECLARATION = 'variable_declaration',
  ASSIGNMENT_EXPRESSION = 'assignment_expression',
  
  // 程序和根节点
  PROGRAM = 'program',
  EXPRESSION_STATEMENT = 'expression_statement'
}

/**
 * TMake抽象语法树(AST)节点接口
 * 表示TMake语言中的语法元素，如标识符、字符串、数字、函数调用等
 */
export interface TMakeASTNode {
  /** 节点类型，使用ASTNodeType枚举中的值 */
  type: string;
  /** 节点的值，根据类型不同而有所不同 */
  value?: any;
  /** 函数调用等节点的参数列表 */
  params?: any[];
  /** 包含子节点的节点（如if语句）的子节点列表 */
  children?: TMakeASTNode[];
  /** 节点在源代码中的行号（用于错误报告） */
  line?: number;
  /** 节点在源代码中的列号（用于错误报告） */
  column?: number;
  /** 节点的原始值（未经处理的形式） */
  rawValue?: any;
}

/**
 * Switch语句AST节点接口
 * 表示"假如"/"是"语句的抽象语法树结构
 */
export interface SwitchStatementNode extends TMakeASTNode {
  type: 'switch_statement';
  /** switch语句的表达式 */
  expression: TMakeASTNode;
  /** case子句列表 */
  cases: (CaseClauseNode | DefaultClauseNode)[];
  /** default子句 */
  defaultCase?: DefaultClauseNode;
}

/**
 * Case子句AST节点接口
 * 表示switch语句中的"是"子句
 */
export interface CaseClauseNode extends TMakeASTNode {
  type: 'case_clause';
  /** case条件表达式 */
  test: TMakeASTNode;
  /** case主体语句 */
  consequent: TMakeASTNode[];
}

/**
 * Default子句AST节点接口
 * 表示switch语句中的"否则"子句
 */
export interface DefaultClauseNode extends TMakeASTNode {
  type: 'default_clause';
  /** default主体语句 */
  consequent: TMakeASTNode[];
}

/**
 * If语句AST节点接口
 */
export interface IfStatementNode extends TMakeASTNode {
  type: 'if_statement';
  /** if条件表达式 */
  test: TMakeASTNode;
  /** if主体语句 */
  consequent: TMakeASTNode[];
  /** else主体语句（可选） */
  alternate?: TMakeASTNode[];
}

/**
 * 函数调用AST节点接口
 */
export interface FunctionCallNode extends TMakeASTNode {
  type: 'function_call';
  /** 函数名称 */
  callee: string;
  /** 函数参数 */
  arguments: TMakeASTNode[];
}

/**
 * 数组表达式AST节点接口
 */
export interface ArrayExpressionNode extends TMakeASTNode {
  type: 'array';
  /** 数组元素 */
  elements: TMakeASTNode[];
}

/**
 * 绳包信息接口
 * 描述TMake项目中使用的绳包（类似库或模块）
 */
export interface PackageInfo {
  /** 绳包名称 */
  name: string;
  /** 绳包路径 */
  path: string;
  /** 绳包中包含的.t文件列表 */
  tFiles: string[];
  /** 绳包依赖的其他绳包列表（可选） */
  dependencies?: string[];
}

/**
 * 编译器配置接口
 * 存储TMake编译器的所有配置选项和生成的配置信息
 */
export interface CompilerConfig {
  /** 输出文件路径 */
  outputFile: string;
  /** 使用的绳包列表 */
  packages: PackageInfo[];
  /** 使用的编译器命令或路径 */
  compiler: string;
  /** 需要链接的动态库列表 */
  dynamicLibraries: string[];
  /** 要编译的源文件列表 */
  sourceFiles: string[];
  /** 编译平台（可选） */
  platform?: string;
  /** 编译模式：调试、发布或硬输出模式 */
  mode?: 'debug' | 'release' | 'hard-mode';
  /** 优化级别 */
  optimizeLevel?: number;
  /** 禁用的lint检查列表 */
  disabledLints?: string[];
  /** 日志级别：调试、信息、警告或错误 */
  logLevel?: 'debug' | 'info' | 'warning' | 'error';
  /** 行号映射文件路径 */
  lineMapPath?: string;
  /** 目标编译平台 */
  platformTarget?: string;
  /** 变量映射表 */
  variables: Record<string, any>;
  /** 解析后的值映射表 */
  resolvedValues: Record<string, any>;
  /** 变量作用域列表 */
  scopes: VariableScope[];
}

/**
 * 变量作用域接口
 * 描述变量的作用域及其包含的变量
 */
export interface VariableScope {
  /** 作用域名称 */
  name: string;
  /** 作用域内的变量映射表 */
  variables: Record<string, any>;
}

// 导出插件系统相关类型
export * from './plugin-system';

/**
 * 函数参数描述接口
 * 定义函数参数的元数据
 */
export interface FunctionParameter {
  /** 参数名称 */
  name: string;
  /** 参数类型 */
  type: string;
  /** 参数描述 */
  description: string;
  /** 是否必需 */
  required: boolean;
  /** 默认值（可选） */
  defaultValue?: any;
}

/**
 * 函数描述接口
 * 定义函数的元数据
 */
export interface FunctionDescription {
  /** 函数名称 */
  name: string;
  /** 函数描述 */
  description: string;
  /** 函数参数列表 */
  parameters: FunctionParameter[];
  /** 返回值类型 */
  returnType: string;
  /** 返回值描述 */
  returnDescription: string;
  /** 函数来源类型：'built-in' 或 'plugin' */
  sourceType: 'built-in' | 'plugin';
  /** 来源名称（如插件名，可选） */
  sourceName?: string;
}

/**
 * 扩展函数接口
 * 定义TMake编译器的扩展函数
 */
export interface ExtensionFunction {
  /** 扩展函数名称 */
  name: string;
  /** 扩展函数描述 */
  description?: string;
  /** 函数参数描述 */
  parameters?: FunctionParameter[];
  /** 返回值类型 */
  returnType?: string;
  /** 返回值描述 */
  returnDescription?: string;
  /** 扩展函数处理函数，接收AST节点、编译器配置、求值器和上下文参数 */
  handler: (node: TMakeASTNode, config: CompilerConfig, evaluate: FunctionEvaluator, context: EvaluationContext) => any;
}

/**
 * 函数求值器类型
 * 用于求值AST节点的函数类型
 */
export type FunctionEvaluator = (node: TMakeASTNode, context?: EvaluationContext) => any;

/**
 * 内置函数接口
 * 定义TMake编译器的内置函数
 */
export interface BuiltInFunction {
  /** 函数名称 */
  name: string;
  /** 函数描述 */
  description: string;
  /** 函数参数描述 */
  parameters: FunctionParameter[];
  /** 返回值类型 */
  returnType: string;
  /** 返回值描述 */
  returnDescription: string;
  /** 函数实现 */
  implementation: (params: any[], node: TMakeASTNode, context: EvaluationContext, compiler: any) => any;
}

/**
 * 求值上下文接口
 * 提供变量查找和函数执行的上下文环境
 */
export interface EvaluationContext {
  /** 当前上下文中的变量映射表 */
  variables: Record<string, any>;
  /** 父级上下文（可选） */
  parent?: EvaluationContext;
}

/**
 * 编译器错误接口
 * 表示编译过程中产生的错误
 */
export interface CompilerError {
  /** 错误类型：语法错误、运行时错误或词法错误 */
  type: 'syntax' | 'runtime' | 'lexical';
  /** 错误消息 */
  message: string;
  /** 错误发生的行号（可选） */
  line?: number;
  /** 错误发生的列号（可选） */
  column?: number;
  /** 错误相关的令牌（可选） */
  token?: string;
  /** 错误详细信息（可选） */
  details?: string;
}

/**
 * 编译结果接口
 * 表示编译过程的最终结果
 */
export interface CompileResult {
  /** 编译是否成功 */
  success: boolean;
  /** 生成的JSON配置（可选） */
  jsonConfig?: string;
  /** 编译过程中产生的错误列表 */
  errors: CompilerError[];
  /** 编译过程中产生的警告列表 */
  warnings: string[];
  /** 生成的抽象语法树（可选） */
  ast?: TMakeASTNode[];
}